Currently there are three types of warps but the syntax was designed to allow future expansion. The first two, the repeat warp and the black_hole warp are new features for POV-Ray that modify the pattern in geometric ways. The other warp provides an alternative way to specify turbulence.

The syntax for using a warp statement in a pigment is

Similarly warps may be used in normals and textures. You may have as many separate warp statements as you like in each pattern. The placement of warp statements relative to other modifiers such as color_map or turbulence is not important. However placement of warp statements relative to each other and to transformations is significant. Multiple warps and transformations are evaluated in the order in which you specify them. For example if you translate, then warp or warp, then translate, the results can be different.

Take, for example, a woodgrain. Using POV-Ray's normal turbulence and other texture modifier functions, you can get a nice, random appearance to the grain. But in its randomness it is regular --- it is regularly random ! Putting in a black hole allows you to create a localised disturbance in a woodgrain in either one or multiple locations. The black hole can have the effect of either 'sucking' the surrounding texture into itself (like the real thing) or 'pushing' it away. In the latter case, applied to a woodgrain, it would look to the viewer as if there were a knothole in the wood. In this text we use a Woodgrain regularly as an example, because it is ideally suitable to explaining Black Holes. However, Black Holes may in fact be used with any texture.

The effect that the black hole has on the texture can be specified; by default, it 'sucks' with the strength calculated expotentially (inverse-square). You can change this if you like.

Black Holes may be used anywhere a Warp is permitted. The syntax is:

Some examples are given by

In order to fully understand how a black hole works, it is important to know the theory behind it. A black hole (or any warp) works by taking a point and 'perturbing' it to another location. The amount of perturbation depends on the strength of the black hole at the original point passed in to it. The amount of perturbation directly relates to the amount of visual movement that you can see occur in a texture. The stronger the black hole at the input co-ordinate, the more that original co-ordinate is moved to another location (either closer to or further away from the center of the black hole.)

Movement always occurs on the vector that exists between the input point and the center of the black hole (which I will now abbreviate BH for brevity).

Black Holes are considered to be spheres. For a point to be affected by a BH, it must be within the sphere's volume.

Suppose you have a BH at <1,1,1>, and a point at <1,2,1>. If this point is perturbed by a total amount of +1 unit, then its new location is <1,3,1>, which is on a direct line extrapolated from the vector between <1,1,1> and <1,2,1>. In this case the point is 'pushed' away from the BH, which is not normal behaviour but is good for demonstration purposes.

The internal properties of a black hole are as follows.

Each of these are discussed below.

Center: A vector defining the center of the sphere that represents the black hole. If the BH has Repeat set, it is the offset within each block.

Radius: A number giving the length, in units, of the radius of the sphere that represents the black hole.

If a point is not within radius units of <center>, it cannot be affected by the BH and will not be perturbed.

Falloff: The power by which the effect of the black hole falls off. The default is two. The force of the black hole at any given point, before applying the 'Strength' modifier, is as follows.

First, convert the distance from the point to the center to a proportion (0 to 1) that the point is from the edge of the black hole. A point on the perimeter of the black hole will be 0.0 ; a point at the centre will be 1.0 ; a point exactly halfway will be 0.5, and so forth.

Mentally you can consider this to be a 'closeness' factor. A closeness of 1.0 is as close as you can get to the center (i.e. *at* the center), a closeness of 0.0 is as far away as you can get from the center and still be inside the black hole, and a closeness of 0.5 means the point is exactly halfway between the two.

Call this value 'C'. Raise C to the power specified in 'Falloff'. By default Falloff is 2, so this is C^2 or C squared. The resulting value is the force of the black hole at that exact location and is used, after applying the 'Strength' scaling factor as described below, to determine how much the point is perturbed in space.

For example, if C is 0.5, then the force is 0.5^2, or 0.25. If C is 0.25, the force is 0.125. But if C is exactly 1.0, the force is 1.0.

Recall that as C gets smaller, the point is farther from the center of the black hole. Using the default power of 2, you can see that as C reduces, the force reduces expotentially in an inverse-square relationship.

Put in plain english, it means that the force is much stronger (by a power of two) towards the center than it is at the outside.

By increasing Falloff, you can increase the magnitude of the falloff ; a large value will mean points towards the perimeter will hardly be affected at all and points towards the center will be affected strongly.

A value of 1.0 for falloff will mean that the effect is linear ; a point that is exactly halfway to the center of the black hole will be affected by a force of exactly 0.5.

A value of Falloff of less than one but greater than zero means that as you get closer to the outside, the force *increases* rather than decreases. This can have some uses but there is a side effect ; recall that the effect of a black hole ceases outside its perimiter. This means that points just within the permiter will be affected strongly and those just outside not at all. This would lead to a visible border, shaped as a sphere.

A value for Falloff of 0 would mean that the force would be 1.0 for all points within the BH, since any number > 0 raised to the power of 0 is 1.0.

The magnitude of the movement of the point is determined basically by the value of force after scaling. We'll consider scaling later. Lets take an example.

Suppose we have a black hole of radius 2.0, and a point that is exactly 1.0 units from the center. That means it is exactly half-way to the center and that C would be 0.5. If we use the default falloff of 2, the force at that point is 0.5^2, or 0.25. What this means is that we must move the point by 0.25 of its distance from the center. In this case it is 1.0 units from the center, so we move it by 1.0*0.25, or 0.25 units. This gives a final distance of 1.0-(1.0*0.25) or 0.75 units from the center, on a direct line in 3D space between the original position and the center.

If the point were part of, say, a wood grain, the wood grain would appear to bend towards the (invisible) center of the BH. If the 'Inverse' flag were set, however, it would be 'pushed' away, meaning its final position would be 1.0+(1.0*0.25), or 1.25 units from the center.

Strength: The 'Strength' gives you a bit more control over how much a point is perturbed by the black hole. Basically, the force of the black hole (as determined above) is multipled by the value of Strength, which defaults to 1.0. If you set Strength to 0.5, for example, all points within the black hole will be moved by only half as much as they would have been. If you set it to 2.0, they will be moved twice as much.

There is a rider to the latter example, though - the movement is clipped to a maximum of the points original distance from the center. That is to say, a point that is 0.75 units from the center may only be moved by a maximum of 0.75 units either towards the center or away from it, regardless of the value of Strength. The result of this clipping is that you will have an 'exclusion' area near the centre of the black hole where all points whose final force value exceeded or equalled 1.0 were moved by a fixed amount.

Inverted: If Inverted is set, points are 'pushed' away from the center instead of being pulled in.

Repeat: Repeat allows you to simulate the effect of many black holes without having to explicitly declare them. Repeat is a vector that tells POV-Ray to use this black hole at multiple locations.

If you're not interested in the theory behind all this, just skim this next text and use the values given in the summary below.

Using repeat logically divides your scene up into cubes, the first being located at <0,0,0> and going to <repeat>. i.e. suppose your repeat vector was <1,5,2>, the first cube would be from <0,0,0> to <1,5,2>. These repeat, so there would be one at <-1,-5,-2>, <1,5,2>, <2,10,4>, and so forth in all directions, ad infinitum.

Instead of the center of the black hole specifying an absolute location in your scene, when you use repeat, the center is an offset into each block. It is only possible to use positive offsets ; using negative values will produce undefined results.

Suppose your center was <0.5,1,0.25> and the repeat vector is <2,2,2>. This gives us a block at <0,0,0> and <2,2,2>, etc. The centers of the BH's for these blocks would be <0,0,0> + <0.5,1.0,0.25> i.e. <0.5,1.0,0.25>, and <2,2,2> + <0.5,1.0,0.25>, i.e. <2,5,3.0,2.25>.

Due to the way repeats are calculated internally, there is a restriction on the values you specify for the repeat vector. Basically, each black hole must be totally enclosed within each block (or cube), with no part crossing into a neighbouring one. This means that, for each of the X, Y and Z dimensions

the offset of the center may not be less than the radius, and the repeat value for that dimension must be >= the center plus the radius

since any other values would allow the black hole to cross a boundary. Put another way, for each of X, Y and Z

radius <= offset of center <= repeat - radius

If the repeat vector in any dimension is too small to fit this criteria, it will be increased and a warning message issued. If the center is less than the radius it will also be moved but no message will be issued.

Note that none of the above should be read to mean that you can't overlap black holes. You most certainly can and in fact this can produce some most useful effects. The restriction only applies to elements of the *same* black hole which is repeating. You can declare a second black hole that also repeats, and its elements can quite happily overlap the first and causing the appropriate interactions.

It is legal for the repeat value for any dimension to be 0, meaning that POV-Ray will not repeat the black hole in that direction.

Turbulence: Turbulence can only be used with repeat. It allows an element of randomness to be inserted into the way the black holes repeat, to cause a more 'natural' look. A good example would be an array of knotholes in wood --- it would look rather artificial if each knothole were an exact distance from the previous.

The 'turbulence vector' is a measurement that is added to each individual back hole in an array, after each axis of the vector is multipled by a different random amount ranging from 0 to 1.

For example, suppose you have a repeating element of a BH that is supposed to be at <2,2,2>. You have specified an turbulence vector of <4,5,3>, meaning you want the position to be able to vary by no more than 1.0 units in the X direction, 3.0 units in the Y direction and 2.0 in Z. This means that the valid ranges of the new position are as follows

X can be from 2 to 6.

Y can be from 2 to 7.

Z can be from 2 to 5.

The resulting actual position of the black hole's center for that particular repeat element is random (but consistent, so renders will be repeatable) and somewhere within the above co-ordinates.

There is a rider on the use of turbulence, which basically is the same as that of the repeat vector ; you can't specify a value which would cause a black hole to potentially cross outside of its particular block.

Since POV-Ray doesn't know in advance how much a position will be changed due to the random nature of the changes, it enforces a rule that is similar to the one for repeat, except it adds the maximum possible variation for each axis to the center. For example, suppose you had a black hole with a center of <1.0, 1.0, 1.0>, radius of 0.5, and a turbulence of <0.5, 0.25, 0> --- normally, the mimimum repeat would be <1.5, 1.5, 1.5>. However, now we take into account the turbulence, meaning the minimum repeat vector is actually <2.0, 1.75, 1.5>.

Repeat summarized: For each of X, Y and Z, the offset of the center must be >= radius, and the value of the repeat must be >= center + radius + turbulence, the exception being that repeat may be 0 for any dimension, which means do not repeat in that direction.